kleur

What is kleur?

The kleur npm package is a library for formatting terminal text with ANSI colors. It provides a simple and chainable API to style strings that are output to the console with various colors, backgrounds, and text styles.

What are kleur's main functionalities?

Coloring text

This feature allows you to apply text color to your console output. The example shows how to color the text green.

const kleur = require('kleur');
console.log(kleur.green('Hello world!'));

Chaining styles

Kleur supports chaining multiple styles together. In this example, the text 'Error!' is styled to be red, bold, and underlined.

const kleur = require('kleur');
console.log(kleur.red().bold().underline('Error!'));

Background colors

You can also set background colors for your text. Here, the text 'Info' has a blue background with white foreground color.

const kleur = require('kleur');
console.log(kleur.bgBlue().white('Info'));

Conditional styling

Kleur allows conditional styling, where you can enable or disable colors based on certain conditions. In this example, the red color is applied only if the environment is not production.

const kleur = require('kleur');
const enabled = process.env.NODE_ENV !== 'production';
console.log(kleur.enabled(enabled).red('Only styled if not in production'));

Other packages similar to kleur

chalk

Chalk is a popular npm package similar to kleur that allows for styling terminal strings. It offers a more extensive API and additional features like template literal support and custom themes, but it is slightly larger in size compared to kleur.

colors

Colors is another package that provides ANSI color formatting for text in the terminal. It extends String.prototype to add color properties, which some developers may find less clean than the functional approach taken by kleur.

ansi-colors

Ansi-colors is a lightweight package that focuses on performance. Like kleur, it does not extend String.prototype and has a chainable API, but it has fewer dependencies and is designed to be as minimal as possible.

README

The fastest Node.js library for formatting terminal text with ANSI colors~!

Features

• No dependencies
• Super lightweight & performant
• Supports nested & chained colors
• No String.prototype modifications
• Conditional color support
• Familiar API

---

As of v3.0 the Chalk-style syntax (magical getter) is no longer used.
If you need or require that syntax, consider using ansi-colors, which maintains chalk parity.

---

Install

$ npm install --save kleur

Usage

const { red, white, blue, bold } = require('kleur');

// basic usage
red('red text');

// chained methods
blue().bold().underline('howdy partner');

// nested methods
bold(`${ white().bgRed('[ERROR]') } ${ red().italic('Something happened')}`);

Chained Methods

console.log(bold().red('this is a bold red message'));
console.log(bold().italic('this is a bold italicized message'));
console.log(bold().yellow().bgRed().italic('this is a bold yellow italicized message'));
console.log(green().bold().underline('this is a bold green underlined message'));

Nested Methods

const { yellow, red, cyan } = require('kleur');

console.log(yellow(`foo ${red().bold('red')} bar ${cyan('cyan')} baz`));
console.log(yellow('foo ' + red().bold('red') + ' bar ' + cyan('cyan') + ' baz'));

Conditional Support

Toggle color support as needed; kleur includes simple auto-detection which may not cover all cases.

const kleur = require('kleur');

// manually disable
kleur.enabled = false;

// or use another library to detect support
kleur.enabled = require('color-support').level;

console.log(kleur.red('I will only be colored red if the terminal supports colors'));

API

Any kleur method returns a String when invoked with input; otherwise chaining is expected.

It's up to the developer to pass the output to destinations like console.log, process.stdout.write, etc.

The methods below are grouped by type for legibility purposes only. They each can be chained or nested with one another.

Colors:

black — red — green — yellow — blue — magenta — cyan — white — gray — grey

Backgrounds:

bgBlack — bgRed — bgGreen — bgYellow — bgBlue — bgMagenta — bgCyan — bgWhite

Modifiers:

reset — bold — dim — italic* — underline — inverse — hidden — strikethrough*

^{* Not widely supported}

Benchmarks

Using Node v10.13.0

Load time

chalk       :: 14.543ms
kleur       ::  0.474ms
ansi-colors ::  1.923ms

Performance

# All Colors
  ansi-colors  x 199,381 ops/sec ±1.04% (96 runs sampled)
  chalk        x  12,107 ops/sec ±2.07% (87 runs sampled)
  kleur        x 715,334 ops/sec ±0.30% (93 runs sampled)

# Stacked colors
  ansi-colors  x 24,494 ops/sec ±1.03% (93 runs sampled)
  chalk        x  2,650 ops/sec ±2.06% (85 runs sampled)
  kleur        x 75,798 ops/sec ±0.19% (97 runs sampled)

# Nested colors
  ansi-colors  x  77,766 ops/sec ±0.32% (94 runs sampled)
  chalk        x   5,596 ops/sec ±1.85% (86 runs sampled)
  kleur        x 137,660 ops/sec ±0.31% (93 runs sampled)

Credits

This project originally forked Brian Woodward's awesome ansi-colors library.

Beginning with kleur@3.0, the Chalk-style syntax (magical getter) has been replaced with function calls per key:

// Old:
c.red.bold.underline('old');

// New:
c.red().bold().underline('new');

^{As I work more with Rust, the newer syntax feels so much better & more natural!}

If you prefer the old syntax, you may migrate to ansi-colors. Versions below kleur@3.0 have been deprecated.

License

MIT © Luke Edwards